E.g., this has neither good function nor parameter name, and so comments need to do all the heavy lifting:

// function to convert temperature from Fahrenheit to Celsius scale
// temp is the temperature in Fahrenheit
double unitConverter(double temp)

Contrast it with this:

double fahrenheitToCelsius(double tempFahrenheit)

We don’t even need a comment here!

For example, using j for outermost and i for nested loop is confusing!

  for (let j = 0; j < arr.length; j++) {
    for (let i = 0; i < arr[j].length; i++) {

Similarly

• tmp shouldn’t be used to store objects that are not temporary
• retVal shouldn’t be used for objects not returned from function
• etc.

All variables are temporary in some sense. Calling one tmp is inviting carelessness.

# generic name
if (right < left) {
  tmp   <- right
  right <- left
  left  <- tmp
}

# more descriptive
if (right < left) {
 old_right <- right
 right     <- left
 left      <- old_right
}

For example, these names are inconsistent since the reader can’t safely assume the name size means the same thing throughout the program.

// context-1: `size` stands for number of memory bytes
{
  size = sizeof(x);
}

// context-2: `size` stands for number of elements
{
  size = strlen(a);
}

You can typically find a middle ground between too short and too long names.

# not ideal - too imprecise
d
# okay - can use more precision
days 

# good - middle ground
days_since_last_accident 

# not ideal - unnecessarily precise
days_since_last_accident_floor_4_lab_23 

...

E.g., here is a GUI text editor class method to get position of a character:

std::tuple<int, int> getCharPosition(int x, int y)

How I interpret: “x and y refer to pixel positions for a character.”

In reality: “x and y refer to line of text and character position in that line.”

You can avoid such misinterpretation with better names:

std::tuple<int, int> getCharPosition(int lineIndex, int charIndex)

E.g., this plotting function uses identifier p to represent a scatter plot object.

plotScatter <- function() {
  p <- ggplot(mtcars, aes(wt, mpg)) + geom_point()
  p <- p + labs(title = "my first scatter plot")
  p
}

In the future, it won’t be easy either to search for and/or to rename it in the code base because searching for p would flag all ps (e.g. ggplot), and not just the one corresponding to the plot object.

Instead, if scatter_plot identifier is used, both search and replace operations will be straightforward.

For example, C++ convention is to use PascalCase for class names and lowerCamel case for variables.

// non-conventional
class playerEntity
{
public:
    std::string HairColor;
};

// conventional
class PlayerEntity
{
public:
    std::string hairColor;
};

Use positive terms for Booleans since they are easier to process.

# double negation - difficult
is_firewall_disabled = FALSE

# better
is_firewall_enabled = TRUE

For example, let’s say your class has $getMeans() method.

• In its initial implementation, it used to return precomputed mean values.
• In its current implementation, it computes the mean values on the fly.

Therefore, it is misleading to continue to call it a getter method, and it should be renamed to (e.g.) $computeMeans().

If you are writing a function to generate a time-stamp, discussing the following function verbally would be challenging.

# generate year month date hour minute second
genymdhms()

This is a much better (and pronounceable) alternative:

generateTimeStamp()

Additionally, avoid naming separate entities with homonyms.

Discussing entities named waste and waist is inevitably going to lead to confusion.

E.g., two similar methods here have different names across R6 classes:

CreditCardAccount$new()$retrieve_expenditure()
DebitCardAccount$new()$fetch_expenditure()

Both of these methods should either be named $retrieve_expenditure() or $fetch_expenditure().

• Don’t use slang. You can’t assume current or future developers to be familiar with them. E.g. exit() is better than hit_the_road().

• Avoid unintended meanings. Do your due diligence to check dictionaries (especially Urban dictionary!) if the word has unintended meaning. E.g. cumulative_sum() is a better function name than cumsum().

• Avoid imprecise opposites, since they can be confusing. E.g. parameter combination begin/last is worse than either begin/end or first/last.

• Don’t use hard-to-distinguish character pairs in names (e.g., l and I, O and 0, etc.). With certain fonts, it can be hard to distinguish firstl from firstI.

• Don’t misspell to save a few characters. Remembering spelling is difficult, and remembering correct misspelling even more so. E.g. don’t use hilite instead of highlight. Benefit is not worth the cost here.

• Don’t use commonly misspelled words in English. Using such names for variables can, at minimum, slow you down, or, at worst, increase the possibility of making an error. E.g. is it accumulate, accummulate, acumulate, or acummulate?!

• Don’t allow multiple English standards. E.g. using both American and British English standards would’ve you constantly guessing if the variable is named (e.g.) centre or center. Adopt one standard and stick to it.

• Don’t use similar names for entities with different meanings. E.g. patientRecs and patientReps are easily confused because they are so similar. There should be at least two-letter difference: patientRecords and patientReports.